Skip to main content

Interstitial

An interstitial ad is a fullscreen format, usually skippable after the first few seconds of its display. Because of this, it's commonly used in transitions of the app or game, such as completing a level or navigating to a different screen.

To start using interstitial ads, just call load() (or Load()/present()/Show() depending on platform) using a valid placement id and then use one of the available present/show functions when you need it to be displayed.

Start loading an interstitial​

#include "x3mads/XMediatorAds.hpp"
// Initialize the SDK once, then load an interstitial
x3mads::XMediatorAds::getInstance()->startWith(
    "<your-app-key>",
    x3mads::InitSettings(),
    [](const x3mads::InitResult& result) {
        x3mads::XMediatorAds::getInstance()->interstitial->load("<placement-id>");
    }
);

Showing an interstitial​

Calling isReady() returns whether an interstitial is available to be shown, regardless of placement ID. If multiple ads with different placement IDs were previously loaded, the SDK will try to show the best one available.

if (x3mads::XMediatorAds::getInstance()->interstitial->isReady()) {
    x3mads::XMediatorAds::getInstance()->interstitial->show();
}
info

You don't need to check isReady() before calling show(). If there isn't an ad ready, your listener's onFailedToShow(...) will be called.

Auto loading​

Ads that are dismissed or fail to show automatically trigger a new load request.

Auto retry​

Failed loads will be retried with exponential backoff.

Additional settings​

Add listener​

Every ad callback indicates the placement ID of the interstitial that triggered the event.

// Register interstitial callbacks via a listener
struct MyInterstitialListener : public x3mads::InterstitialAdsListener {
    void onImpression(const std::string& placementId, const x3mads::ImpressionData& data) override {
        CCLOG("Interstitial impression! placementId: %s", placementId.c_str());
    }
    void onClicked(const std::string& placementId) override {
        CCLOG("Interstitial clicked! placementId: %s", placementId.c_str());
    }
    void onLoaded(const std::string& placementId, const x3mads::LoadResult& result) override {
        CCLOG("Interstitial loaded! placementId: %s", placementId.c_str());
    }
    void onShowed(const std::string& placementId) override {
        CCLOG("Interstitial is being shown! placementId: %s", placementId.c_str());
    }
    void onFailedToShow(const std::string& placementId, const x3mads::Error& error) override {
        // If you need to resume your app's flow, do it here and in onDismissed
        CCLOG("Interstitial failed to show. placementId: %s", placementId.c_str());
    }
    void onDismissed(const std::string& placementId) override {
        // If you need to resume your app's flow, do it here and in onFailedToShow
        CCLOG("Interstitial dismissed! placementId: %s", placementId.c_str());
    }
};

auto listener = new MyInterstitialListener();
x3mads::XMediatorAds::getInstance()->interstitial->addListener(listener);

Remove listener​

If you add a listener, you should remove it when your scene/object is destroyed to stop receiving events.

void InterstitialExample::cleanup()
{
    x3mads::XMediatorAds::getInstance()->interstitial->removeListener(listener);
    Scene::cleanup();
}

Showing an interstitial with ad space​

x3mads::XMediatorAds::getInstance()->interstitial->showFromAdSpace("ad-space");

Showing an interstitial with placement ID​

Calling isReady("<placement-id>") returns whether an interstitial is available to be shown.

if (x3mads::XMediatorAds::getInstance()->interstitial->isReady("<placement-id>")) {
    // show without ad space
    x3mads::XMediatorAds::getInstance()->interstitial->show("<placement-id>");
    // or show with ad space
    x3mads::XMediatorAds::getInstance()->interstitial->show("<placement-id>", "ad-space");
}

Code example​

Below is a Cocos2d-x example showing how to load, check readiness, and show an interstitial.

InterstitialExample.cpp
void showInterstitial()
{
    auto* sdk = x3mads::XMediatorAds::getInstance();
    if (sdk->interstitial->isReady()) {
        sdk->interstitial->show();
    }
}

x3mads::XMediatorAds::getInstance()->startWith(
    "<your-app-key>", 
    x3mads::InitSettings(), 
    [=](const x3mads::InitResult&) {
        x3mads::XMediatorAds::getInstance()->interstitial->addListener(this);
        x3mads::XMediatorAds::getInstance()->interstitial->load("<placement-id>");
    }
);